Attribute Release Policies

The attribute release policy decides how attributes are selected and provided to a given application in the final CAS response. Additionally, each policy has the ability to apply an optional filter to weed out their attributes based on their values.

The following settings are shared by all attribute release policies:

Name Value
authorizedToReleaseCredentialPassword Boolean to define whether the service is authorized to release the credential as an attribute.
authorizedToReleaseProxyGrantingTicket Boolean to define whether the service is authorized to release the proxy-granting ticket id as an attribute.
excludeDefaultAttributes Boolean to define whether this policy should exclude the default global bundle of attributes for release.
authorizedToReleaseAuthenticationAttributes Boolean to define whether this policy should exclude the authentication/protocol attributes for release. Authentication attributes are considered those that are not tied to a specific principal and define extra supplementary metadata about the authentication event itself, such as the commencement date.
principalIdAttribute An attribute name of your own choosing that will be stuffed into the final bundle of attributes, carrying the CAS authenticated principal identifier.
Usage Warning!

Think VERY CAREFULLY before turning on the above settings. Blindly authorizing an application to receive a proxy-granting ticket or the user credential may produce an opportunity for security leaks and attacks. Make sure you actually need to enable those features and that you understand the why. Avoid where and when you can, specially when it comes to sharing the user credential.

CAS makes a distinction between attributes that convey metadata about the authentication event versus those that contain personally identifiable data for the authenticated principal.

Actuator Endpoints

The following endpoints are provided by CAS:


Authentication Attributes

During the authentication process, a number of attributes get captured and collected by CAS to describe metadata and additional properties about the nature of the authentication event itself. These typically include attributes that are documented and classified by the underlying protocol or attributes that are specific to CAS which may describe the type of credentials used, successfully-executed authentication handlers, date/time of the authentication, etc.

Releasing authentication attributes to service providers and applications can be controlled to some extent.

The following settings and properties are available from the CAS configuration catalog:

The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.authn.authentication-attribute-release.enabled=true

    • Whether CAS authentication/protocol attributes should be released as part of ticket validation.

    org.apereo.cas.configuration.model.core.authentication.AuthenticationAttributeReleaseProperties.
  • cas.authn.authentication-attribute-release.never-release=

    • List of authentication attributes that should never be released.

    org.apereo.cas.configuration.model.core.authentication.AuthenticationAttributeReleaseProperties.
  • cas.authn.authentication-attribute-release.only-release=

    • List of authentication attributes that should be the only ones released. An empty list indicates all attributes should be released.

    org.apereo.cas.configuration.model.core.authentication.AuthenticationAttributeReleaseProperties.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    Protocol/authentication attributes may also be released conditionally on a per-service basis.

    Principal Attributes

    Principal attributes typically convey personally identifiable data about the authenticated user, such as address, last name, etc. Release policies are available in CAS and documented below to explicitly control the collection of attributes that may be authorized for release to a given application.

    Remember

    Depending on the protocol used and the type/class of service (i.e. relying party) registered with CAS, additional release policies may become available that allow more fine-tuned control over attribute release, catering better to the needs of the particular authentication protocol at hand. Remember to verify attribute release capabilities of CAS by visiting and studies the appropriate documentation for each protocol.

    Default

    CAS provides the ability to release a bundle of principal attributes to all services by default. This bundle is not defined on a per-service basis and is always combined with attributes produced by the specific release policy of the service, such that for instance, you can devise rules to always release givenName and cn to every application, and additionally allow other specific principal attributes for only some applications per their attribute release policy.

    The following settings and properties are available from the CAS configuration catalog:

    The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.authn.attribute-repository.core.default-attributes-to-release=

    • CAS provides the ability to release a bundle of principal attributes to all services by default. This bundle is not defined on a per-service basis and is always combined with attributes produced by the specific release policy of the service, such that for instance, you can devise rules to always release givenName and cn to every application, and additionally allow other specific principal attributes for only some applications per their attribute release policy.

    org.apereo.cas.configuration.model.core.authentication.PrincipalAttributesCoreProperties.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    Return All

    Return all resolved principal attributes to the service, and optionally exclude attributes from the final collection.

    1
2
3
4
5
6
7
8
9
10

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 100,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnAllAttributeReleasePolicy",
    "excludedAttributes": ["java.util.LinkedHashSet", ["cn"]]
  }
}

    Return Static

    Return static attributes to the service with values hard-coded in the service definition.

    1
2
3
4
5
6
7
8
9
10
11
12
13

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 100,
  "attributeReleasePolicy" : {
    "@class": "org.apereo.cas.services.ReturnStaticAttributeReleasePolicy",
    "allowedAttributes": {
      "@class": "java.util.LinkedHashMap",
      "permissions": [ "java.util.ArrayList", [ "read", "write", "admin" ] ]
    }
  }
}

    Attribute values can use the Spring Expression Language syntax.

    Deny All

    Never ever return principal attributes to applications. Note that this policy also skips and refuses to release default attributes, if any.

    1
2
3
4
5
6
7
8
9
10

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 100,
  "description" : "sample",
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.DenyAllAttributeReleasePolicy"
  }
}

    Return Allowed

    Only return the principal attributes that are explicitly allowed by the service definition.

    1
2
3
4
5
6
7
8
9
10

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 100,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnAllowedAttributeReleasePolicy",
    "allowedAttributes" : [ "java.util.ArrayList", [ "cn", "mail", "sn" ] ]
  }
}

    Attributes authorized and allowed for release by this policy may not necessarily be available as resolved principal attributes and can be resolved on the fly dynamically using the attribute definition store.

    Return Encrypted

    Encrypt and encode all all allowed attributes in base-64 using the assigned registered service public key.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 100,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnEncryptedAttributeReleasePolicy",
    "allowedAttributes" : [ "java.util.ArrayList", [ "cn", "mail", "sn" ] ]
  },
  "publicKey" : {
    "@class" : "org.apereo.cas.services.RegisteredServicePublicKeyImpl",
    "location" : "classpath:public.key",
    "algorithm" : "RSA"
  }
}

    The keys can be generated via the following commands:

    1
2
3

    openssl genrsa -out private.key 1024
openssl rsa -pubout -in private.key -out public.key -inform PEM -outform DER
openssl pkcs8 -topk8 -inform PER -outform DER -nocrypt -in private.key -out private.p8

    Attributes authorized and allowed for release by this policy may not necessarily be available as resolved principal attributes and can be resolved on the fly dynamically using the attribute definition store.

    REST

    Only return the principal attributes that are explicitly allowed by contacting a REST endpoint. Endpoints must be designed to accept/process application/json. The expected response status code is 200 where the body of the response includes a Map of attributes linked to their values.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 100,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnRestfulAttributeReleasePolicy",
    "endpoint" : "https://somewhere.example.org",
    "headers": {
      "@class": "java.util.LinkedHashMap",
      "header": "value"
    }
  }
}

    The following parameters are passed to the endpoint:

    Parameter Description
    principal The object representing the authenticated principal.
    service The object representing the corresponding service definition in the registry.

    The body of the submitted request may also include a Map of currently resolved attributes.

    Return Mapped

    Similar to above, this policy will return a collection of allowed principal attributes for the service, but also allows those principal attributes to be mapped and “renamed” at the more granular service level.

    For example, the following configuration will recognize the resolved attributes eduPersonAffiliation and groupMembership and will then release affiliation and group to the web application configured.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "description" : "sample",
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnMappedAttributeReleasePolicy",
    "allowedAttributes" : {
      "@class" : "java.util.TreeMap",
      "eduPersonAffiliation" : "affiliation",
      "groupMembership" : "group"
    }
  }
}

    Attributes authorized and allowed for release by this policy may not necessarily be available as resolved principal attributes and can be resolved on the fly dynamically using the attribute definition store.

    Return MultiMapped

    The same policy may allow attribute definitions to be renamed and remapped to multiple attribute names, with duplicate attributes values mapped to different names.

    For example, the following configuration will recognize the resolved attribute eduPersonAffiliation and will then release affiliation and personAffiliation whose values stem from the original eduPersonAffiliation attribute while groupMembership is released as group. In other words, the eduPersonAffiliation attribute is released twice under two different names each sharing the same value.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnMappedAttributeReleasePolicy",
    "allowedAttributes" : {
      "@class" : "java.util.TreeMap",
      "eduPersonAffiliation" : [ "java.util.ArrayList", [ "affiliation", "personAffiliation" ] ],
      "groupMembership" : "group"
    }
  }
}

    Attributes authorized and allowed for release by this policy may not necessarily be available as resolved principal attributes and can be resolved on the fly dynamically using the attribute definition store.

    Pattern Matching

    This policy allows the release of defined allowed attributes only if the attrribute value(s) matches the given regular expression pattern. If the attribute value is matched successfully, the policy is then able to apply transformation rules on the value to extract and collect the matched groups to then assemble the final attribute value.

    For example, consider an authenticated principal with a memberOf attribute which contains values such as CN=g1,OU=example,DC=org, and CN=g2,OU=example,DC=org. The following policy applies the defined pattern and the transformation on each attribute value. The final result would be a memberOf attribute with values g1@example.org and g2@example.org.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class": "org.apereo.cas.services.PatternMatchingAttributeReleasePolicy",
    "allowedAttributes": {
        "@class": "java.util.TreeMap",
        "memberOf": {
            "@class": "org.apereo.cas.services.PatternMatchingAttributeReleasePolicy$Rule",
            "pattern": "^CN=(\\w+),\\s*OU=(\\w+),\\s*DC=(\\w+)",
            "transform": "${1}@${2}/${3}"
        }
    }
  }
}

    Matched pattern groups typically start at 1. If you need to refer to the entire matched region, use ${0}.

    Inline Groovy Attributes

    Principal attributes that are mapped may produce their values from an inline groovy script. As an example, if you currently have resolved a uid attribute with a value of piper, you could then consider the following:

    1
2
3
4
5
6
7
8
9
10
11
12
13

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnMappedAttributeReleasePolicy",
    "allowedAttributes" : {
      "@class" : "java.util.TreeMap",
      "uid" : "groovy { return attributes['uid'].get(0) + ' is great' }"
    }
  }
}

    In the above snippet, the value of the uid attribute name is mapped to the result of the inline groovy script. Inline scripts always begin with the syntax groovy {...} and are passed the current collection of resolved attributes as an attributes binding variable. The result of the script can be a single/collection of value(s).

    The above configuration will produce a uid attribute for the application whose value is a concatenation of the original value of uid plus the words “ is great”, so the final result would be “piper is great”.

    File-based Groovy Attributes

    Identical to inline groovy attribute definitions, except the groovy script can also be externalized to a .groovy file:

    1
2
3
4
5
6
7
8
9
10
11
12
13

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnMappedAttributeReleasePolicy",
    "allowedAttributes" : {
      "@class" : "java.util.TreeMap",
      "uid" : "file:/etc/cas/sample.groovy"
    }
  }
}

    The sample.groovy script itself may have the following outline:

    1
2
3
4
5
6
7
8

    import java.util.*

def run(final Object... args) {
    def attributes = args[0]
    def logger = args[1]
    logger.debug("Current attributes are {}", attributes)
    return []
}

    The configuration of this component qualifies to use the Spring Expression Language syntax.

    Groovy Script

    Let an external Groovy script decide how principal attributes should be released. The configuration of this component qualifies to use the Spring Expression Language syntax.

    1
2
3
4
5
6
7
8
9
10

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.GroovyScriptAttributeReleasePolicy",
    "groovyScript" : "classpath:/script.groovy"
  }
}

    The script itself may be designed in Groovy as:

    1
2
3
4
5
6
7
8
9
10
11

    import java.util.*

def run(final Object... args) {
    def currentAttributes = args[0]
    def logger = args[1]
    def principal = args[2]
    def service = args[3]

    logger.debug("Current attributes received are {}", currentAttributes)
    return [username:["something"], likes:["cheese", "food"], id:[1234,2,3,4,5], another:"attribute"]
}

    The following parameters are passed to the script:

    Parameter Description
    currentAttributes Map of attributes currently resolved and available for release.
    logger The object responsible for issuing log messages such as logger.info(...).
    principal The object representing the authenticated principal.
    service The object representing the corresponding service definition in the registry.

    Script Engines

    Usage

    This feature is deprecated and is scheduled to be removed in the future.

    Use alternative script engine implementations and other programming languages to configure attribute release policies. This approach takes advantage of scripting functionality built into the Java platform via additional libraries and drivers. While Groovy should be natively supported by CAS, the following module is required in the overlay to include support for additional languages such as Python, etc.

    1
2
3
4
5

    <dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-support-script-engines</artifactId>
  <version>${cas.version}</version>
</dependency>

    1

    implementation "org.apereo.cas:cas-server-support-script-engines:${project.'cas.version'}"

    1
2
3
4
5
6
7
8
9

    dependencyManagement {
  imports {
    mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
  }
}

dependencies {  
  implementation "org.apereo.cas:cas-server-support-script-engines"
}

    The service definition then may be designed as:

    1
2
3
4
5
6
7
8
9
10

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ScriptedRegisteredServiceAttributeReleasePolicy",
    "scriptFile" : "classpath:/script.[py|js|groovy]"
  }
}

    The configuration of this component qualifies to use the Spring Expression Language syntax. The scripts need to design a run function that receives a list of parameters. The collection of current attributes in process as well as a logger object are passed to this function. The result must produce a map whose keys are attributes names and whose values are a list of attribute values.

    As an example, the script itself may be designed in Groovy as:

    1
2
3
4
5
6
7
8
9

    import java.util.*

def Map<String, List<Object>> run(final Object... args) {
    def currentAttributes = args[0]
    def logger = args[1]

    logger.debug("Current attributes received are {}", currentAttributes)
    return[username:["something"], likes:["cheese", "food"], id:[1234,2,3,4,5], another:"attribute"]
}

    Here’s the same script written in Python:

    1
2
3
4
5

    def run(*Params):
  Attributes = Params[0]
  Logger = Params[1]
  # Calculate attributes and return a new dictionary of attributes...
  return ...

    You are also allowed to stuff inlined groovy scripts into the scriptFile attribute. The script has access to the collection of resolved attributes as well as a logger object.

    1
2
3
4
5
6
7
8
9
10

    {
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "sample",
  "name" : "sample",
  "id" : 300,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ScriptedRegisteredServiceAttributeReleasePolicy",
    "scriptFile" : "groovy { return attributes }"
  }
}

    Attribute Repository Filtering

    Attribute release policies can be assigned a principalAttributesRepository to consult attribute sources defined and controlled by Person Directory attribute repositories to fetch, resolve, cache and release attributes. To learn more about this topic, please see this guide.

    Chaining Policies

    Attribute release policies can be chained together to process multiple rules. See this guide to learn more.

    Attribute Value Filters

    While each policy defines what principal attributes may be allowed for a given service, there are optional attribute filters that can be set per policy to further weed out attributes based on their values.

    See this guide to learn more.